RFD: https://agentclientprotocol.com/rfds/streamable-http-websocket-transport

Other Implementations

• feat(transports): add HTTP/WebSocket transport support rust-sdk#162
• RFD: Streamable HTTP & WebSocket Transport typescript-sdk#155

This PR adds support for the HTTP SSE protocol for both client and server.

// HTTP
AcpAgentFactory factory = AcpAgentFactory.async(transport -> AcpAgent.async(transport)
    .initializeHandler(req -> Mono.just(new InitializeResponse(
        AcpSchema.LATEST_PROTOCOL_VERSION,
        new AgentCapabilities(true, null, null),
        List.of()
    )))
    .newSessionHandler(req -> Mono.just(new NewSessionResponse("session-1", null, null)))
    .promptHandler((req, ctx) -> ctx.sendMessage("Hello from HTTP").thenReturn(PromptResponse.endTurn()))
    .build());

var server = new StreamableHttpAcpAgentTransport(
    8080,
    AcpJsonMapper.createDefault(),
    factory
);

server.start().block();
server.awaitTermination().block();

// WS
AcpAgentFactory factory = AcpAgentFactory.async(transport -> AcpAgent.async(transport)
    .initializeHandler(req -> Mono.just(new InitializeResponse(
        AcpSchema.LATEST_PROTOCOL_VERSION,
        new AgentCapabilities(true, null, null),
        List.of()
    )))
    .newSessionHandler(req -> Mono.just(new NewSessionResponse("session-1", null, null)))
    .promptHandler((req, ctx) -> ctx.sendMessage("Hello from WebSocket").thenReturn(PromptResponse.endTurn()))
    .build());

var server = new RemoteWebSocketAcpAgentTransport(
    8080,
    AcpJsonMapper.createDefault(),
    factory
);

server.start().block();
server.awaitTermination().block();

Remaining Work

• Implement WS spec from RFD; Revisit per-logical-session active-prompt tracking in AcpAgentSession
• Refactor WS Agent Session to use a shared routing/dispatch core

Open Questions

Implementation specific notes / questions

1. I've introduced a strict and compatible mode, to allow stricter protocol adherence. This can be helpful for debugging paths, but I don't see an existing pattern for this so I am not sure if this is good to include.

2. Client handler return-value forwarding: I noticed that in the WS version, the transport client was forwarding the client handler's return message. For example, a request permission message would be returned to the server. There should be no handler registered, so the server would return a "-32601 Method not found". I've Mirrored WS behaviour for compatibility, but I think this is a bug. And opened a separate PR to discuss.

3. When a method is not recognized, in compatible mode we try to pass through as Session scoped / Route scoped based on presence of session id. This might be a RFD question as well. But this logic is in the transport layer, which maybe is not appropriate.

4. validateClientResponseScope handles mismatching requests as warnings, this is same as existing WS behaviour, but might be codified in the protocol. This seems safe since server is source of truth and there's no follow up action that can be taken inherently since its trying to associate a response to non-existent request. Agent behaviour isn't affected, but we might be able to do better from a protocol design POV.

5. The AcpAgentSession assumes a single active prompt because in WS its one connection one session. But with HTTP, there's . So we will probably need to do nudge users to a new interface for WS and HTTP to remain compatible.

6. I have a test harness to test the correctness in an integration test in a language agnostic way. I was thinking we could use this as a way to test implementation across languages. It doesn't belong in this SDK, but I still wanted to share to get some feedback.

RFD clarifications that I'll follow up on

1. Compatible provisional session/load streams, I went with the same approach as the Rust implementation by introducing a PENDING_LOAD state. But I'll raise in Tulip to officially include.
2. Method not recognized behaviour needs more specification. The Rust, TS, and Java implementation options are different levels of strictness. Passthrough behaviour, and session-scope detection.